Time-based label views#

Scripting provides a set of convenient time-related label components that wrap SwiftUI's Text styles. These components allow you to display live-updating or formatted date and time strings in widgets and views, with support for dynamic behaviors like relative time and timers.

DateLabel#

Displays a dynamic label representing a single point in time using a specified style. This is ideal for widgets that need to show time-based data even when not actively running.

Props#

1type DateLabelProps = {
2  timestamp: number
3  style: 'date' | 'time' | 'timer' | 'relative' | 'offset'
4}

• timestamp: A UNIX timestamp in milliseconds representing the date to be

• style: The display style. Can be:

  • "date": e.g. "June 3, 2019"

  • "time": e.g. "11:23PM"

  • "timer": a running timer string

  • "relative": e.g. "2 hours, 23 minutes"

  • "offset": e.g. +2 hours, -3 months

Example#

1<DateLabel
2  timestamp={Date.now()}
3  style="date"
4/>
5
6<DateLabel
7  timestamp={Date.now()}
8  style="timer"
9/>

DateRangeLabel#

Displays a localized textual representation of a time range between two dates.

Props#

1type DateRangeLabelProps = {
2  from: number
3  to: number
4}

Example#

1<DateRangeLabel
2  from={Date.now()}
3  to={Date.now() + 1000 * 60}
4/>

DateIntervalLabel#

Displays a formatted time interval, typically between two times on the same day (e.g., for event scheduling).

Props#

Same as DateRangeLabelProps:

1type DateIntervalLabelProps = {
2  from: number
3  to: number
4}

Example#

1let fromDate = new Date()
2fromDate.setHours(9)
3fromDate.setMinutes(30)
4
5let toDate = new Date()
6toDate.setHours(15)
7toDate.setMinutes(30)
8
9<DateIntervalLabel
10  from={fromDate.getTime()}
11  to={toDate.getTime()}
12/>

Output example: "9:30 AM – 3:30 PM"

TimerIntervalLabel#

Displays a live-updating timer counting up or down between two timestamps. Optionally, the timer can pause at a specific point.

Props#

1type TimerIntervalLabelProps = {
2  from: number
3  to: number
4  pauseTime?: number
5  countsDown?: boolean
6  showsHours?: boolean
7}

Example#

1<TimerIntervalLabel
2  from={Date.now()}
3  to={Date.now() + 1000 * 60 * 12}
4  pauseTime={Date.now() + 1000 * 60 * 10}
5/>

This displays a countdown from 12 minutes and pauses at the 10-minute mark.